Random URL is a CGI application for Mac web servers. This CGI randomly returns an url, from a text file, to clients. This program is shareware - see below for details.
Features
* WebSTAR server Action support
* Pre-indexing of files for faster response time
* Compiled application (written in C) means fast response time
* Can be used for random pictures in html documents.
Installation and Setting Up
Installing the CGI
Put the CGI where you want it in your http folder hierarchy. You will only be able to access URL text files (or aliases to them) that are in the same folder, or within a subfolder of the folder that the Random URL CGI is in. So, you will quite likely want to put the CGI in the root folder of your http server hierarchy
The CGI is sufficiently fast at returning results that you're best to leave it as a CGI instead of an ACGI.
You should set up a default file of urls to randomly return (see below for details on creating the indexed url text files). It must be in the same folder as the Random URL CGI. It must also have the same name as the cgi with ".rnd" appended to the end of the name. So, if the cgi is named "random.cgi", the default text file should be named "random.cgi.rnd".
A sample file "random.cgi.rnd" that has already been indexed (but can be re-indexed if you want to try that out) is included with the Random URL CGI.
Creating Indexed URL Text Files
The Random URL CGI depends on text files to contain the urls it returns.
You can create many separate text files containing the urls to be randomly chosen from. The text files can have any format of newline (Macintosh format carriage returns, UNIX linefeeds or dos crlf pairs). Do not put any characters in the text file aside from the urls and the newlines. Do not put in any blank lines. You may leave the very last line blank (terminating newline at the end of the file) but that is not required.
You will want to pre-index the text files. This is done either through the "Index URL Text File…" menu item, or by dragging the files onto the icon of the "random.cgi" application. If you want to index a file that isn't explicitly defined as a TEXT file, hold down the option key when selecting the "Index URL Text File…" menu item.
Important: any time you change the text file you MUST manually re-index it - it will NOT be automatically updated by the CGI if the file was previously indexed. (hopefully I'll have this fixed in a future version.)
If the Random URL CGI receives a CGI request for a file that hasn't been indexed, it will try to index the file on the spot. Please note that this will increase the amount of time it will take to respond to that request (although all subsequent requests for that file will have the advantage of an already indexed file).
Calling the CGI from your HTML documents
If you just refer to the CGI by itself, it will attempt to use the default indexed url text file (described above). IE. http://my.server.com/random.cgi
You can use the path arguments (the stuff following the dollar sign '$') to specify files in the same folder as the Random URL CGI, or lower in the folder hierarchy. If you are specifying a file contained in a folder lower than the CGI's folder, the path arguments must begin with a colon ':' - or rather the encoded form of a colon '%3A'. Additionaly, folder and file names must be separated by a colon. Note that if there is more than one colon at the begining of the path arguments, all but one will be ignored so that no files outside of your http hierarchy can be accessed. If you want to access an indexed url text file outside of your http hierarchy, make an alias to it and put that alias somewhere in the folders that the Random URL CGI can access.
So, if I have my CGI installed as "HardDrive:http:random.cgi", I can specify the file "HardDrive:http:pictures.random" with the url:
http://my.server.com/random.cgi$pictures.random
Also, the file "HardDrive:http:work:project:template:sample.list" can be specified with the url:
You have to put the "random.cgi" application in the root folder of the WebSTAR hierarchy, but you can name it wherever you want. This description assumes the cgi is named "random.cgi" and is in the root folder of the http server hierarchy.
In the WebSTAR Admin program, choose "Actions" from the "Configure" menu. This will bring up the "Actions" dialog.
- In the "Application:" field, enter ":random.cgi" to specify the location of the cgi.
- In the "Action Name:" field, you can enter whatever you want but I recommend "random".
- Finally (for this dialog) click the "Add" button, then the "Update" button.
That will allow you to then choose "random" as an action in the "Suffix Mapping" (MIME Type) dialog.
Bring up the "Suffix Mapping" dialog using the "Configure" menu.
- Select "RANDOM" as the action.
- Set the "File Suffix:" to ".RND" (or whatever you want to use).
- Set the "File Type:" to "TEXT" and the "Creator:" to "RUrl" (the creator id of the Random URL CGI).
- The "MIME Type:" is irrelevant since it doesn't apply to redirection as done by the cgi, so just set it to "text/html".
- Click the "Add" button, then use the arrows to move the new mapping to where you want it in the list of suffix mappings.
- When you're done, click the "Update" button.
Now, whenever you refer to a file with the suffix ".rnd" (case insensitive) in your WebSTAR folder hierarchy, it will be processed by the Random URL CGI. For example, if I have my CGI installed as "HardDrive:http:random.cgi" (where "http" is the folder that WebSTAR is in), I can specify the file "HardDrive:http:pictures.rnd" with the url:
http://my.server.com/pictures.rnd
Also, the file "HardDrive:http:work:project:template:sample.rnd" can be specified with the url:
Follow the guidelines for setting up the CGI (either as a normal CGI or as a WebSTAR Action). Next, set up your Indexed URL Text File with a list of urls pointing to graphic files (preferably gifs - since that's what most browsers can view). Finally, in your html document set your image tag to point to your Indexed URL Text File. For example:
<IMG SRC="http://my.server.com/random.cgi$pictures.rnd" ALT="a random picture">
Other Application Details
If any file accessed by the Random URL CGI is a Finder alias, the alias will be resolved to find the original file. (this only works for files, not folders.)
The application can be set to automatically quit after a given period of inactivity. This is configurable through the "Options" menu. Balloon Help is available for the menus and the Preferences dialog box.
Limitations
File Size: 32767 bytes maximum size. Anything larger will not be used.
URL Size: 4095 characters maximum.
Total URLs: 32767. But then, you can't fit that many into a 32767 byte file anyway.
This is beta software but it seems to actually work without problems! Don't bet your life on it though...
Further Information About This CGI
World Wide Web home page:
http://arpp.carleton.ca/cgi/random.html
Grant's CGI Discussion & Announcements mail list:
I've set up a mailing list for discussing the framework on which this CGI is based. It is intended to be a forum for information, ideas, questions and announcements about CGIs written by me, and about writing CGIs using Grant's CGI Framework.
Send a message with the command "subscribe" as the subject to:
grantcgi@arpp.carleton.ca
Download:
http://arpp.carleton.ca/cgi/random.sit.hqx
Source Code:
This application is based on "Grant's CGI Framework" which is available at:
http://arpp.carleton.ca/cgi/framework/
http://arpp.carleton.ca/cgi/grantscgi.sit.hqx
and on info-mac mirror sites.
The additional code specific to this project is not available.
Legal Stuff:
See the "License and Limited Warranty" document for all the usual boring details.
Shareware
If you like this software and decide to continue to use it for more than 28 days, you must purchase a license the author. Each license entitles you to run as many copies of the software as you want on a single machine. Additional machines require additional licenses.
* Commercial users: US$15 (Canadians pay CDN$15 no GST)
* Non-profit users: US$5 (Canadians pay CDN$5 no GST)
* Site License: US$50 (Canadians pay CDN$50 no GST)
* World-wide Site License: US$275 (Canadians pay CDN$275 no GST)
(Canadian prices only apply to payments sent directly to Grant Neufeld - not through Kagi Shareware - from Canadians only)
Add $1 if you want a paper receipt.
Registered users will receive the following via internet email:
1) A 'Fat' Random URL CGI
2) A PowerPC Random URL WebSTAR plug-in
(Fat means it includes native code versions for both PowerPC and 680x0)
Registered users are also entitled to ask for new features.
You MUST include your internet email address when making payment to receive the 'FAT' Random URL.
Payment
Payment can be made by cheque or cash (mail cash at your own risk!) in US or Canadian dollars payable to Grant Neufeld and mailed to:
Grant Neufeld
1002, 210 Gloucester Street
Ottawa, Ontario
K2P 2K4 Canada
Include your name, postal address, and email.
All other payment types should be made via Kagi Shareware.
Paying Through Kagi Shareware (the Register Program)
Paying for through Kagi is fairly simple. Open the Register program that accompanies Random URL. Enter your name, your email address, and the number of single user licenses you desire for each program you wish to purchase (or Site or Word-Wide licenses). Save or Copy or Print the data from the Register program and send the data and payment to Kagi.
If paying with Credit Card or First Virtual, you can email or fax the data to Kagi. Their email address is sales@kagi.com and their fax number is +1 510 652-6589. You can either Copy the data from Register and paste into the body of an email message or you can Save the data to a file and you can attach that file to an email message. There is no need to compress the data file, it's already pretty small. If you have a fax modem, just Print the data to the Kagi fax number.
Payments sent via email are processed within 3 to 4 days. You will receive an email acknowledgement when it is processed. Payments sent via fax take up to 10 days and if you provide a correct internet email address you will receive an email acknowledgement.
If you are paying with Cash or USD Check you should print the data using the Register application and send it to the address shown on the form, which is:
Kagi
1442-A Walnut Street #392-GN
Berkeley, California 94709-1405
USA
You can pay with a wide variety of cash from different countries but at present if you pay via check, it must be a check drawn in US Dollars. Kagi cannot accept checks in other currencies, the conversion rate for non-USD checks is around USD 15 per check and that is just not practical. If you have a purchasing department, you can enter all the data into the Register program and then select Invoice as your payment method. Print three copies of the form and send it to your accounts payable people. You might want to highlight the line that mentions that they must include a copy of the form with their payment.
Kagi can not invoice your company, you need to act on Kagi's behalf and generate the invoice and handle all the paper work on your end. Please do not fax or email payment forms that indicate Cash, Check or Invoice as the payment method. There is still no technology to transfer physical objects via fax or email and without the payment, the form cannot be processed.
Payments sent via postal mail take time to reach Kagi and then up to 10 days for processing. Again, if you include a correct email address, you will hear from Kagi when the form is processed.
Possible Future Enhancements
The following are things I would like to do to improve this CGI. Note that the more I receive in shareware fees, the more features will be implemented.
* Multiple files for more urls in one random selection
* Eliminate limitations on file size and total number of urls (or at least expand the limits to accommodate larger files and more urls)
* Find and index urls in any text file (not just strict format currently used)
* Preferences option to include only selected URL types (e.g., "http:", "ftp:")
* Deal properly with blank lines in the url list text file and define a means of putting comments into the file
* Recognize when the text file has been modified more recently than the index and automatically update it
* 'Weighting' of urls so that you can set the relative percentage of times individual url will be returned.
Version History
• 1.0b3
- Upgraded to "Grant's CGI Framework" 1.0b16 which includes many new features and bug fixes. Most notable among these is the new "Options" menu and "Preferences" dialog. See the balloon help for details on using these new features.
- Various bug fixes including (hopefully) fixing the problem running on servers that don't support the "ACTION" parameter (most notably, MacHTTP).
- cheezy new spinning cursor when indexing files.
- Changed command-key for "Pre-Index URL Text File..." to 'O' instead of 'I'.
• 1.0b2
- Can now handle any combination of carriage returns and linefeeds.
- Menu item "Index URL Text File…" added.
- Cursor switches to watch while indexing a file.
- Status window pops up to indicate success or failure of Indexing an URL text file.
- Path argument support (stuff after $ in an url)
- WebSTAR Action support
- Finder alias file resolving (won't try to mount unmounted volumes, so no user interface calls will be made)
- Stopped all known memory leaks.
- Some bug fixes.
• 1.0b1 - First release.
About the Author
Grant Neufeld is the author of "Grant's CGI Framework" (which Random URL is made with), and the "Mac WWW FAQ".
See my CGIs pages for information about my other CGI projects:
http://arpp.carleton.ca/cgi/
The Mac WWW FAQ:
http://arpp.carleton.ca/mac/
See my vanity page for more insight into who I am and what I do:
http://arpp.carleton.ca/grant/
Contacting me (use one of):
gneufeld@ccs.carleton.ca
grant@kagi.com
grant@acm.org
____________________
Macintosh and Mac are trademarks or registered trademarks of Apple Computer, Inc.
StarNine and WebSTAR are trademarks of StarNine Technologies, Inc.
UNIX is a registered trademark of Novell, Inc.
WorkSMART is a trademark of InfoDesign Corporation.
